package net.oxygen.upload.service;

import net.oxygen.upload.dto.FileInfoDTO;
import net.oxygen.upload.model.FileDO;
import net.oxygen.upload.request.FileSecondUploadReq;
import net.oxygen.upload.request.FileUploadReq;

import java.util.List;

/**
 * 文件服务接口V2
 * <p>
 * 该接口提供文件的上传、秒传、查询和删除等核心功能
 * 相比V1版本，提供了更完善的文件管理功能：
 * - 支持文件秒传
 * - 增强的文件列表查询功能
 * - 优化的文件存储逻辑
 * </p>
 *
 * @author chenweiwei
 * @version 2.0
 * @since 2023-03-24
 */
public interface IFileV2Service {

    /**
     * 保存文件信息
     * <p>
     * 将文件元数据保存到数据库，用于记录文件基本信息和存储位置
     * </p>
     * 
     * @param req       文件上传请求，包含文件名、大小等基本信息
     * @param objectKey 文件在存储服务中的唯一键，格式通常为 日期/MD5.扩展名
     * @return 文件信息数据库实体对象
     */
    FileDO saveFile(FileUploadReq req, String objectKey);

    /**
     * 上传小体积文件
     * <p>
     * 用于处理体积较小的文件上传，直接将文件上传到存储服务
     * 一般适用于小于5MB的文件，避免分片上传的复杂性
     * </p>
     * 
     * @param req 文件上传请求，包含文件对象和元数据
     */
    void upload(FileUploadReq req);

    /**
     * 大文件秒传
     * <p>
     * 基于文件的唯一标识（通常是MD5值）判断服务器是否已存在相同文件
     * 如果存在，则无需实际上传文件内容，直接创建引用关系
     * 此功能可显著提高大文件上传效率，减少网络传输
     * </p>
     * 
     * @param req 文件秒传请求，包含文件唯一标识、文件名、大小等信息
     * @return 秒传是否成功，true表示秒传成功，false表示需要走正常上传流程
     */
    boolean secondUpload(FileSecondUploadReq req);

    /**
     * 获取文件列表
     * <p>
     * 查询已上传的文件列表，支持按文件名模糊搜索和分页查询
     * 返回的文件信息包含基本元数据和预签名的访问URL
     * </p>
     *
     * @param fileName 文件名关键字，用于模糊查询，可为null
     * @param pageNum  页码，从1开始
     * @param pageSize 每页记录数
     * @return 文件信息列表，包含文件的详细信息和访问链接
     */
    List<FileInfoDTO> list(String fileName, Integer pageNum, Integer pageSize);

    /**
     * 删除文件
     * <p>
     * 根据文件的唯一标识删除文件，包括：
     * 1. 从存储服务中删除文件对象
     * 2. 从数据库中标记文件记录为已删除
     * </p>
     *
     * @param identifier 文件唯一标识（通常是MD5值）
     */
    void delete(String identifier);
}
